feat: System Bars Plugin #8180

theproducer · 2025-10-03T14:38:16Z

This PR introduces a new core plugin, System Bars, designed to be a modern take on the Status Bar plugin, managing Android System Bars, the iOS status bar, and fix issues related to broken safe area insets on Android.

pauldemarco · 2025-10-15T20:58:29Z

This looks great, what more is needed before merge?

pauldemarco · 2025-10-15T23:31:30Z

I am noticing that currently, without this plugin, the safe area and the status bar are working great on iOS -- it even changes the status bar text depending on light or dark mode when I toggle dark on the root: document.documentElement.classList.toggle('dark')

I am noticing this PR includes some styling on the status bar. Is there any way to have Android act like the iOS and have it "just work"?

I also want to make sure this won't break what we have working fine on iOS.

tafelnl · 2025-10-16T06:29:15Z

I am noticing this PR includes some styling on the status bar. Is there any way to have Android act like the iOS and have it "just work"?

I also want to make sure this won't break what we have working fine on iOS.

I am not sure if you have a correct understanding of this "inject css variables" thing. It doesn't inject env css variables, as that isn't possible. It detects the safe area insets in a best effort and injects them as custom var css variables. That means that you will have to change code to make it work on both iOS and Android. That's exactly one of the reasons I'm advocating for a native approach

tafelnl · 2025-10-16T09:22:37Z

I'd like to add that as of November 1st (actually earlier, but Google granted an extension to developers that depend on older SDKs) no one will be able to publish a release to the play store if they're not supporting edge-to-edge. So I think this should be given the utmost priority by the Capacitor team

pauldemarco · 2025-10-16T15:01:45Z

I am noticing this PR includes some styling on the status bar. Is there any way to have Android act like the iOS and have it "just work"?
I also want to make sure this won't break what we have working fine on iOS.

I am not sure if you have a correct understanding of this "inject css variables" thing. It doesn't inject env css variables, as that isn't possible. It detects the safe area insets in a best effort and injects them as custom var css variables. That means that you will have to change code to make it work on both iOS and Android. That's exactly one of the reasons I'm advocating for a native approach

I just discovered all of this was only a problem with an Android Medium emulator. I just tried the Pixel 9 emulator and safe area is working great without any plugins.

theproducer · 2025-10-20T22:46:43Z

Hello everyone! Stay tuned, I'm on the verge of getting this past the finish line, The plan is to make some final changes and wrap this up this week.

theproducer · 2025-10-20T22:52:32Z

I am noticing this PR includes some styling on the status bar. Is there any way to have Android act like the iOS and have it "just work"?

By "just work", you're expecting just the default status bar, without the fullscreen / transparent status bar style, correct?

tafelnl · 2025-10-21T06:59:46Z

I'm curious which approach you've chosen to go with. I'm still advocating for going the native route. To demonstrate how that would work I made a simple demo proof of concept. Mind you that I've created this in like 5 minutes, so it's still not perfect, but you will get the main idea.

Demo: https://github.com/tafelnl/capacitor-demo
The magic happens in this file: https://github.com/tafelnl/capacitor-demo/blob/main/android/app/src/main/java/com/example/demo/EdgeToEdgePlugin.kt

I also commented some todos which I haven't done because it's a proof of concept.

pauldemarco · 2025-10-22T17:09:49Z

I am noticing this PR includes some styling on the status bar. Is there any way to have Android act like the iOS and have it "just work"?

By "just work", you're expecting just the default status bar, without the fullscreen / transparent status bar style, correct?

As of right now on iOS, without this plugin, the status bar is transparent and switches the text color automatically to the right color when I set the root html class to dark mode and light mode. Not sure how this is working.

core/systembars.md

android/capacitor/src/main/java/com/getcapacitor/plugin/SystemBars.java

riderx · 2025-10-29T07:28:47Z

Thanks @theproducer for this; this is much needed !
Long ago I made this: https://github.com/Cap-go/capacitor-home-indicator
who was also made to help on that matter, I do think both are needed.
I do believe both should be core API :)
I'm up to implement it if needed

theproducer · 2025-11-03T16:56:51Z

Thanks @theproducer for this; this is much needed ! Long ago I made this: https://github.com/Cap-go/capacitor-home-indicator who was also made to help on that matter, I do think both are needed. I do believe both should be core API :) I'm up to implement it if needed

I think being able to control iOS's home indicator fits in to the use case here, thanks for the suggestion!

riderx · 2025-11-03T18:44:46Z

Something i found out doing this plugin is hide and show doesn’t naturally update the css var for safe areas, so that something to take in account that would let us easy have reactive design. During my session i was not able to update the real value so i had to create new var. if you know how to handle this i would be glad ti be included too.
I know ionic framework has hack for that with ionic var, but it will be nice to have a generic solution who work for all, and documented in the website:)
Safe areas is a constant topic of beginners :)

tafelnl · 2025-11-06T11:04:04Z

Not sure how this PR relates to it, but you might want to take a look at this PR: ionic-team/capacitor-plugins#2388

tafelnl · 2025-11-07T09:33:47Z

I think it makes sense to remove the workaround logic from the keyboard plugin and incorporate it in the capacitor core/this PR. Otherwise all users would have to install the keyboard plugin in order to make it work correctly

android/capacitor/src/main/java/com/getcapacitor/plugin/SystemBars.java

tafelnl · 2025-11-07T09:40:24Z

android/capacitor/src/main/java/com/getcapacitor/plugin/SystemBars.java

+            Insets safeArea = insets.getInsets(WindowInsetsCompat.Type.systemBars() | WindowInsetsCompat.Type.displayCutout());
+            injectSafeAreaCSS(safeArea.top, safeArea.right, safeArea.bottom, safeArea.left);


I think in this case we should fallback to logic similar as to what adjustMarginsForEdgeToEdge does.

Also injecting the safe area insets as custom vars should be a toggleable option I think. And only respected if hasMetaViewportCover==true imo, so it stays consistent with the native inset behavior

I think in this case we should fallback to logic similar as to what adjustMarginsForEdgeToEdge does.

You are referring to adding margins directly to the native view? That was meant to be a quick and dirty fix - we generally try to avoid manipulating the native views style-wise as much as possible to leave the power and final decision making in the hands of the web developer.

Using CSS env vars (albeit a bit convoluted because of the Android bug: var(--safe-area-inset-top, env(safe-area-inset-top, 0px));) would be the normal way of handling edge to edge behavior, and we want to stick as close to that as possible. Additionally, we have other requirements depending on these injected vars.

Also injecting the safe area insets as custom vars should be a toggleable option I think.

This is something we can do, I'll work on adding a config option for disabling the inset injections altogether.

You are referring to adding margins directly to the native view

Yes that's what I meant. It would align with iOS behavior. If a user does not enable edge-to-edge support through the viewport-fit=cover tag, the webview itself will already add margins for you. Otherwise every capacitor developer would need to add support for env variables. Which would be a major breaking change.

Ideally, of course, this is something that the Android team will just natively support out of the box. But iirc a few years/months ago one of the devs mentioned that it's not something they were looking into. I cannot find the comment anymore. I'll link it if I come across it

Co-authored-by: Tafel <[email protected]>

tafelnl · 2025-11-07T14:22:55Z

I think it makes sense to remove the workaround logic from the keyboard plugin and incorporate it in the capacitor core/this PR. Otherwise all users would have to install the keyboard plugin in order to make it work correctly

Actually, upon better looking into this, I think the workaround as is can be removed altogether. Instead we should do something like this inside the setOnApplyWindowInsetsListener

Insets systemBarsInsets = windowInsets.getInsets(WindowInsetsCompat.Type.systemBars() | WindowInsetsCompat.Type.displayCutout());
Insets imeInsets = windowInsets.getInsets(WindowInsetsCompat.Type.ime());
boolean keyboardVisible = windowInsets.isVisible(WindowInsetsCompat.Type.ime());

ViewGroup.MarginLayoutParams mlp = (ViewGroup.MarginLayoutParams) parent.getLayoutParams();
if (keyboardVisible) {
    // https://issues.chromium.org/issues/457682720
    // this is a workaround to push the webview behind the keyboard for webview versions that have a bug
    // that causes the bottom inset to be incorrect if the IME is visible
    boolean hasWebViewWithKeyboardBug = true; // chromium version with this bugfix is yet to be released, so the version is unknown still
    if (hasWebViewWithKeyboardBug) {
        mlp.bottomMargin = imeInsets.bottom - systemBarsInsets.bottom;
    } else {
        mlp.bottomMargin = imeInsets.bottom;
    }
} else {
    mlp.bottomMargin = 0;
}
parent.setLayoutParams(mlp);

return windowInsets;

parent can be either bridge.getWebView() or (ViewGroup) getBridge().getWebView().getParent(). Not sure which is better

I think this is much cleaner than the current workaround. Additionally it makes the workaround also work across config changes such as rotating the screen (the current workaround would break, which is a bug currently)

OS-pedrogustavobilro

Haven't fully finished reviewing, but leaving some comments questions, for now mostly minor stuff / documentation

OS-pedrogustavobilro · 2025-11-07T16:39:40Z

core/src/core-plugins.ts

+  /**
+   * The style is based on the device appearance or the underlying content.
+   * If the device is using Dark mode, the statusbar text will be light.
+   * If the device is using Light mode, the statusbar text will be dark.
+   *
+   * @since 8.0.0
+   */


Minor: technically it's not just the text right?

Suggested change

/**

* The style is based on the device appearance or the underlying content.

* If the device is using Dark mode, the statusbar text will be light.

* If the device is using Light mode, the statusbar text will be dark.

*

* @since 8.0.0

*/

/**

* The style is based on the device appearance or the underlying content.

* If the device is using Dark mode, the system bars content will be light.

* If the device is using Light mode, the system bars will be dark.

*

* @since 8.0.0

*/

OS-pedrogustavobilro · 2025-11-07T16:43:06Z

core/src/core-plugins.ts

+   * Style of the text and icons of the system bars.
+   *
+   * @since 8.0.0
+   * @default default


Should be?

Suggested change

* @default default

* @default 'DEFAULT'

OS-pedrogustavobilro · 2025-11-07T16:43:26Z

cli/src/declarations.ts

+   */
+  SystemBars?: {
+    /**
+     * The style of the text and icons of the system bars.


Missing what would be the default value? 'DEFAULT'?

OS-pedrogustavobilro · 2025-11-07T16:44:14Z

cli/src/declarations.ts

+    style?: string;
+
+    /**
+     * Hide the system bars on start.


Missing what would be the default value? "false"?

OS-pedrogustavobilro · 2025-11-07T17:16:19Z

core/systembars.md

@@ -0,0 +1,273 @@
+# SystemBars
+
+The SystemBars API provides methods for configuring the style and visibility of the device System Bars / Status Bar.  This API differs from the [Status Bar](https://capacitorjs.com/docs/apis/status-bar) plugin in that it is only intended to support modern edge to edge use cases moving forward.  For legacy functionality, use the [Status Bar](https://capacitorjs.com/docs/apis/status-bar) plugin.


I think we could use more information on how this core plugin works with status-bar, and when to use one or the other or both.

Unsure if this should reside here, in status bar documentation, or somewhere, just wanted to bring it up.

OS-pedrogustavobilro · 2025-11-07T17:26:36Z

core/src/core-plugins.ts

+  setAnimation(options: SystemBarsAnimationOptions): Promise<void>;
+}
+
+export class SystemBarsPluginWeb extends WebPlugin implements SystemBarsPlugin {


Correct me if I'm wrong but this core plugin will become the first (or at least the only one for Capacitor currently) that is only available in native mobile apps, not in web.

While for a lot of people this not being available in web would be obvious, maybe for some it wouldn't be. Wondering if we should make that explicit somewhere in the docs.

OS-pedrogustavobilro · 2025-11-07T17:33:43Z

ios/Capacitor/Capacitor/Plugins/SystemBars.swift

+        if let style = getConfig().getString("style") {
+            setStyle(style: style)
+        }


Minor: don't think this matters much, but on Android we're using the 'DEFAULT' value to explicitly set the style. Unsure if it matters much, since it should load with a default style, just wanted to mention this since it seems like a minor inconsistency.

OS-pedrogustavobilro · 2025-11-07T17:39:13Z

android/capacitor/src/main/java/com/getcapacitor/plugin/SystemBars.java

+                          document.documentElement.style.setProperty("--safe-area-inset-right", "%dpx");
+                          document.documentElement.style.setProperty("--safe-area-inset-bottom", "%dpx");
+                          document.documentElement.style.setProperty("--safe-area-inset-left", "%dpx");
+                          window.dispatchEvent(new CustomEvent('safeAreaChanged'));


What is this 'safeAreaChanged' event for? Something specific to Android WebView?

OS-pedrogustavobilro · 2025-11-07T18:04:10Z

ios/Capacitor/Capacitor/Plugins/SystemBars.swift

+        CAPPluginMethod(name: "hide", returnType: CAPPluginReturnNone)
+    ]
+
+    public var hideHomeIndicator: Bool = false


Don't need this to be set outside of this class right? Or do we? If not, then

Suggested change

public var hideHomeIndicator: Bool = false

public private(set) var hideHomeIndicator: Bool = false

OS-pedrogustavobilro · 2025-11-07T18:09:29Z

ios/Capacitor/Capacitor/Plugins/SystemBars.swift

+        let inset = call.getString("inset")?.uppercased()
+
+        if let animation = call.getString("animation") {
+            setAnimation(animation: animation)


Minor: if we're uppercasing the style, we could do it for animation as well? Here in show, in loading config, and hide?

theproducer added 14 commits September 15, 2025 15:24

Setting on core definitions and docs for SystemBars plugin

2b49827

Renaming, adding basic docs

b78f69f

Adding Android SystemBars basic functionality

edb5288

Adding Android safe area injection

3bb5784

fmt

6ddb7b9

Adding insets support to setting style and hiding

9e6b41a

Starting on overlay webview support

2c93ccd

Cleanup, adding support for configuration

c4be18d

Fixes to type declarations

11c5590

Updating meaning of LIGHT vs DARK

07d6b3f

Updating style to match documentation on iOS

0698ca7

Rename enable to enableInsets

8bcd46d

Merge branch 'main' into RDMR-902

15fab3a

fmt

bf2fe33

tafelnl mentioned this pull request Oct 21, 2025

Adding in the edge to edge behavior that comes standard with cordova-android to our OutSystems branch. OutSystems/cordova-android#27

Closed

5 tasks

theproducer added 4 commits October 22, 2025 11:49

Removing overlay support

bbfb49b

Adding webview version check, optimizing insets injection

c6664d1

fmt

55717fd

Merge branch 'main' into RDMR-902

0f7d843

Adding config option for hiding system bars

ba72a20

tafelnl mentioned this pull request Oct 22, 2025

Safe Area Insets Still Not Working in v7 and Chromium 140+ After Package Sunset capacitor-community/safe-area#68

Closed

theproducer added 5 commits October 22, 2025 16:47

Making showing / hiding status bars more friendly

114367d

naming and consistency

e8df7ae

documentation

7eb6aed

docs, fmt

6fb8d70

fmt

a104cea

theproducer requested review from ItsChaceD, OS-pedrogustavobilro, alexgerardojacinto, andredestro, jcesarmobile and markemer October 23, 2025 14:54

theproducer marked this pull request as ready for review October 23, 2025 14:55

tafelnl reviewed Oct 27, 2025

View reviewed changes

core/systembars.md Show resolved Hide resolved

tafelnl reviewed Oct 27, 2025

View reviewed changes

android/capacitor/src/main/java/com/getcapacitor/plugin/SystemBars.java Outdated Show resolved Hide resolved

theproducer added 2 commits October 27, 2025 12:46

Removing enableInsets setting in exchange for meta viewport checking

7ca256c

Removing Cap 7 edgeToEdgeHandler

21f473b

theproducer added 3 commits November 3, 2025 08:50

Merge branch 'main' into RDMR-902

be27917

Adding ability to control iOS home indicator visibility

cd2fb6c

fmt

cf0b1f9

Readding adjustMarginsForEdgeToEdge, defaulted to “auto”

ec05a18

tafelnl reviewed Nov 7, 2025

View reviewed changes

android/capacitor/src/main/java/com/getcapacitor/plugin/SystemBars.java Outdated Show resolved Hide resolved

tafelnl reviewed Nov 7, 2025

View reviewed changes

webview and viewport check fix

984a254

Co-authored-by: Tafel <[email protected]>

OS-pedrogustavobilro reviewed Nov 7, 2025

View reviewed changes

		Insets safeArea = insets.getInsets(WindowInsetsCompat.Type.systemBars() \| WindowInsetsCompat.Type.displayCutout());
		injectSafeAreaCSS(safeArea.top, safeArea.right, safeArea.bottom, safeArea.left);

		@@ -0,0 +1,273 @@
		# SystemBars

		The SystemBars API provides methods for configuring the style and visibility of the device System Bars / Status Bar. This API differs from the [Status Bar](https://capacitorjs.com/docs/apis/status-bar) plugin in that it is only intended to support modern edge to edge use cases moving forward. For legacy functionality, use the [Status Bar](https://capacitorjs.com/docs/apis/status-bar) plugin.

	public var hideHomeIndicator: Bool = false
	public private(set) var hideHomeIndicator: Bool = false

feat: System Bars Plugin #8180

Are you sure you want to change the base?

feat: System Bars Plugin #8180

Uh oh!

Conversation

theproducer commented Oct 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pauldemarco commented Oct 15, 2025

Uh oh!

pauldemarco commented Oct 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

tafelnl commented Oct 16, 2025

Uh oh!

tafelnl commented Oct 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pauldemarco commented Oct 16, 2025

Uh oh!

theproducer commented Oct 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

theproducer commented Oct 20, 2025

Uh oh!

tafelnl commented Oct 21, 2025

Uh oh!

pauldemarco commented Oct 22, 2025

Uh oh!

Uh oh!

Uh oh!

riderx commented Oct 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

theproducer commented Nov 3, 2025

Uh oh!

riderx commented Nov 3, 2025

Uh oh!

tafelnl commented Nov 6, 2025

Uh oh!

tafelnl commented Nov 7, 2025

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tafelnl commented Nov 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

OS-pedrogustavobilro left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

theproducer commented Oct 3, 2025 •

edited

Loading

pauldemarco commented Oct 15, 2025 •

edited

Loading

tafelnl commented Oct 16, 2025 •

edited

Loading

theproducer commented Oct 20, 2025 •

edited

Loading

riderx commented Oct 29, 2025 •

edited

Loading

tafelnl commented Nov 7, 2025 •

edited

Loading